◊ Installing the debugging version of QuickDraw 3D
◊ API and Developer Tips
◊ 3DMF Notes
◊ 3D Metafiles
◊ Scrapbook and SimpleText
Minimum Configuration Requirements
• Your memory needs will vary wildly depending on the types of geometries you work with and the complexity of the models you use. For example, there is little correlation between the size of a model file made up of NURB patches and the amount of memory that will be required to render such a model, because the constant supplied for subdivision can cause a model to require little memory to render or require hundreds of times the size of the model file to render.
• QuickDraw 3D allocates its memory out of the system heap, using temporary memory. If the system heap fills up, QD3D will attempt to allocate blocks out of the application heap. When this occurs, you will receive a kQ3WarningLowMemory warning. For the convenience of your user, you may want to filter out this warning until your application heap is actually low on memory. In a sense, kQ3WarningLowMemory just lets you know that your application heap is being used for allocations.
When you call Q3Exit, QD3D will deallocate all of its blocks. If your application is killed (via a debugger, etc.), the memory manager will deallocate all blocks allocated by QuickDraw 3D in temp memory.
Installing the debugging version of QuickDraw 3D
• During your development process you should use the debugging version of QuickDraw 3D. To install it, just place the three extension files in the Extensions folder, in the System Folder, and restart your computer. The debugging version has a lager footprint and lower performance, but it has more extensive error checking. Using the debugging version will help you find problems with your code. The debugging version posts Notices in addition to the Errors and Warnings posted by the optimized version.
API and Developer Tips
• In the Macintosh Draw Context, the 2D library field should be set to kQ3Mac2DLibraryNone for release 1.0.
• If you want to use the Unix Storage object in QuickDraw 3D with MetroWerks or any other development system, link against “StdCLib” not “ANSI C.PPC.Lib”. This means you'll also need to shield the MetroWerks ANSI headers using parenthesis (see the MetroWerks users manual if you don't understand how shielding works) and add the path to the MPW headers to your Access Path page in the Preferences dialog. For the few calls that exist only in the MetroWerks version of the ANSI headers and not in the MPW version, you are out of luck for now, until MetroWerks updates their ANSI implementation to depend on StdCLib or until Apple decides to provide a library linked against ANSI C.PPC.Lib (which is very unlikely.)
• If you do not register an error handler (Q3Error_Register), the debugging library will by default call DebugStr when errors occur. If you don't like this behavior, register an error handler which does nothing.
• Q3Exit may return kQ3Failure if leaks occur. This call will always shut down QuickDraw 3D.
• Don't make any QuickDraw 3D calls from inside an error/warning/notice handler other than those that are specifically allowed in the documentation. Making other calls can lead to an Infinite Loop. Please see chapter 19 for more information.
• Immediate-mode while writing
Please note that if you register a custom object with QuickDraw 3D and support the 3 I/O Methods (Traverse/Write/ReadData), there are certain problems with using immediate-mode Q3Foo_Submit calls (to submit subobjects) in your TQ3ObjectTraverseMethod. If you are NOT submitting any subobjects (meaning you return kQ3Success without doing anything, or the ONLY thing you call is Q3View_SubmitWriteData), you don't need to worry about this.
This problem only applies to non-object immediate-mode Q3Foo_Submit calls that take a pointer to data in the application. Therefore, Q3Polygon_Submit and Q3SubdivisionStyle_Submit have this problem, while Q3Style_Submit and Q3InterpolationStyle_Submit are safe.
The data passed to Q3Foo_Submit in every other case (e.g. within a drawing/bounding/picking loop) is used and discarded or copied before returning to the original caller.
The semantics of the TQ3ObjectTraverseMethod are that you MUST call Q3View_SubmitWriteData FIRST, then any other "Submit" call. In this ONE CASE, when you are re-entering QuickDraw 3D's API via a Q3Foo_Submit call, the data is not actually "written" using the "write" method until right before returning to the top-level QD3D API call. This means that whatever you pass to any Q3Foo_Submit call must remain in memory beyond your traverse method call. Since "objects" are retained correctly you may use this as a workaround.
DON'T Do this - the stack will be garbage at the end of this function:
if (Q3Polygon_Submit(&(data->polyData), view) == kQ3Failure)
...
This will be fixed in future releases.
• Before getting the local to world, world to frustrum, and frustrum to window matrices in a submit loop and the current renderer is Interactive be sure to change to the Generic render, submit the views in a submit loop to get the matrices, and change back to the Interactive renderer afterwards. This workaround for the interactive renderer which always clears the buffer image even when the clear image method is set to none. Do this with the following code:
• Setting the draw context's clear image method to none will not prevent the Interactive renderer from clearing the window with the clear image color. This is a "feature" which is meant for various hardware accelerators which may always clear the background to a color regardless. And if you've seen the hardware scream, you don't complain.
• The key aspect of the Interactive Renderer is interactivity. As such, the Interactive Renderer will not do transparency in software, Phong shading, or shadows at this time. Depending on the accelerator card installed, you may get transparency or shadows. To check for the functionality of a specific card, you can use the QuickDraw 3D RAVE calls.
• The "isDirty" flag in the unknown objects (UnknownBinary, UnknownText) is a no-op. It does not affect how that object is written. You must strip out and dispose unwanted unknown objects, otherwise they will be written to the file if its parent object is written.
• Unfortunately, memory is needed to write information to a metafile.
The last thing anyone wants is to hit "Save" and get a tidy little dialog box stating "Sorry, you're out of memory" with one button, "OK." Hopefully, in future releases, you will be able to write to a metafile with NO memory available.
The easiest workaround is to free up memory NOT in your application (QD3D uses the system heap) - and have the user quit other applications (if they are active) via a friendly dialog, etc.
The next easiest workaround is to have some way of freeing up large objects which are generally held around to cache information and are not needed for writing. If you have any renderers, views, or draw contexts around, these are prime targets for disposal, especially if you're doing double-buffered drawing. If you discover mid-write that a "_Submit" call has failed, you should free up as much memory as possible, and attempt to write it again.
If this still fails, as a last-ditch attempt, you should close and cancel the existing file, and use an "emergency" storage and file which your application created and opened in kQ3FileModeStream and started (Q3View_StartWriting) at your application startup.
• Be sure not to place the link libraries (QuickDraw3DLib, <foo>Lib) in the same folder (or in the Extensions folder) as the application you are developing and running, or you will experience problems.
• Do not call Q3File_Cancel during your "idle" method. It WILL crash due to some internal problems. You may cancel the file by returning kQ3Failure.
3DMF Notes
• The official type of QuickDraw 3D Metafiles is '3DMF', regardless of whether the metafile is in "text" mode or in "binary" mode. This type is used for files, resources, and the clipboard.
In general, the end user is not expected to be able to read the text metafile. For development purposes, it's much easier to allow 'TEXT' documents to be read by an application so that "FileTyper" doesn't become a habit. As well, you may wish to add "Power User" options in low-level applications which allow parsing of 'TEXT' metafiles via some input channel. These, however, should be well hidden or require at least 4 modifier keys to access via the keyboard. Well, just kidding, but you get the drift.
• Unknown objects
There are many objects and features in the 3DMF specification which are not implemented in the 1.0 release. A cursory list is: Cone, Cylinder, Sphere, Ellipsoid, Disk, Ellipse, PolyLine, TrimLoops and NURBCurve2D (on NURBPatches), Type objects, external references (MacintoshPath, UnixPath), Unicode. In addition, unknown custom types (below) are read in as unknown objects. When you read these unrecognized 3D metafile objects using QD3D 1.0, you will receive an UnknownText or UnknownBinary object. Beware - unknown objects appear whereever they are encountered, so if you read a group, one may appear within the group. They also may appear in any Shape's Set, if unrecognized custom data appears as a subobject of a shape. You can get at unknown subobjects by calling:
Q3Shape_GetSet(shape, &set);
if (set != NULL)
{
if ((Q3Set_Contains(set, kQ3ElementTypeUnknown)) &&
... convert it to something known or remove it ...
Q3Object_Dispose(obj);
}
Q3Object_Dispose(set);
}
"obj" in the above example will be an unknown object, or a group. Note unknown objects are "shapes", too, so "subobjects" of unknown objects are stored in their "set", etc.
• Custom Types
Please register your custom attributes/elements with Apple. We are still trying to get on-line registration, until we do, please go through DEVSUPPORT. Your proposals need to document the format, as well as the usage, and contain the code to implement the attribute registration/IO/usage. Check out our Web site for more information on this, along with a lot of other helpful information about QD3D and 3DMF parser source code written in C.
In general, you may choose (or may be assigned) a 3-byte type and a string prefix to use for your "name space". The 3-byte type allows you to use the last byte for up to 256 custom data types. You should use the string prefix to secure a portion of the text metafile name space.
So, for example, supposing I worked at "Joe's 3D Modelling, Inc." company. Suppose you were given the 3-byte sequence 'JOE' (0x4A4F45), and the ascii string, "Joe3DCo:". You would then call Q3ElementClass_Register or Q3AttributeClass_Register with a binary type in the range: 0x4A4F4500 - 0x4A4F45FF, with its counterpart in text "Joe3DCo:AnimData", "Joe3DCo:Frames", etc.
Remember that binary-ascii metafiles are always one-to-one, therefore, there is only one binary type for each ascii type. If you need more than 256, apply for another type range.
For those people who have read the 3DMF Spec, I'll bet you're asking, "Well, 3DMF has the ability to declare custom types inline, based on ISO 9070 naming! Why can't we use that?" You can, if you use the parser, and do all the type recognition and binding in your application. In QD3D 1.0 unrecognized objects (listed above) are read in as "UnknownBinary" or "UnknownText" objects. In this case, the "type" object is not a part of the 1.0 feature set, so it is read as unknown. You COULD interpret these unknowns and build the table on your application side, and do all the binding, parsing, etc. - and not have to register with Apple for your custom types! So a little work, or a little effort... which will it be?
• "Bad" metafiles and objects
A word about how QuickDraw 3D's I/O system deals with reading metafiles that contain bad information. In general, many things may go wrong while reading a metafile, both semantically in how objects are arranged, logically in the data that is stored, and physically within the media in which a metafile resides.
Semantic problems come in many forms - in most cases it comes down to what QuickDraw 3D has defined the semantic to be (e.g. you can't place CStrings in DisplayGroups, etc.). Another semantic problem is having subobjects which are not allowed within a container. Some examples of this would be placing a "geometry" as a subobject (within a container) of another geometry, hacing a non-AttributeSet subobject of a VertexAttributeSetList (excluding References, of course), having an extra BeginGroup or EndGroup object, having a non-DAG group structure, or having a "ImageMask" as the subobject of a Translate object, etc.
Other semantic problems are having too little or too much data within an object. For example, an "AttributeSet" that is not of size zero, or a Polygon that is only 4 bytes, or a DisplayGroup not within a BeginGroup container.
QD3D deals with this in some cases: when an object is misplaced as the subobject of a shape object, the object is placed in the shape's set as a kQ3ElementTypeUnknown element. In the remaining cases, semantic problems are dealt with by skipping the unused, unwanted or invalid data.
Logical errors are those in which the data within an object defies the semantics of the specification. A polygon with < 3 vertices, an invalid "label" value within a style, a mesh index that is out of range, etc. In these cases, the object is usually skipped. This may result in partial or skewed data coming from the metafile.
Physical errors, such as hitting end of file or garbage data (unrecognizable or garbage tokens), cause the I/O system to punt, which your app should do as well. In these cases, you may receive a kQ3ErrorMacintoshError, a kQ3ErrorEndOfFile, or a kQ3ErrorInvalidMetafile. If you've received some valid objects in the metafile up to the point of the error, it's your decision to preserve what you can or junk the whole thing.
You should be mostly aware of how these errors may affect reading a metafile. When you call Q3File_ReadObject, more "proper" semantics would be "give me the next object that is not invalid." This call will attempt to read an object and return it to you. If it runs out of memory, it posts that error and returns NULL. You may free up some memory and try again - you are still at the same object. If it finds an object that is improperly formatted, etc. and can skip it, it will try to read the next object instead.
In relation to custom I/O, if you are inside a container in your TQ3ObjectReadData method, Q3File_IsEndOfContainer may be TRUE (you haven't read the next object yet), however, Q3File_ReadObject may return NULL if a subobject is invalid and the end of container has been reached. You should check the error codes and determine if something fatal has occurred or not.
Viewer with Scrapbook, SimpleText
• Viewer General Info
Your application must have at least 32k available in its application heap when creating a Viewer object, or you will get a return value of NULL, which usually signifies out of memory. Also, the Viewer code checks to see that there is 1 MB available in Temp memory.
When using the Viewer, the default center of interest is the center of the model. You can change the center of interest by clicking on the model while holding down the "Command" key. To reset the center of interest to the center of the model, click outside the model while holding down the "Command" key.
• Scrapbook and SimpleText memory usage.
Scrapbook and SimpleText uses system temp memory when viewing 3DMF models, so if you
run out of memory don't increase the application memory size. Try quitting other running
applications to free up memory.
• SimpleText and System 7.1.2
To run SimpleText with 3DMF viewing support under System 7.1.2 you must install the
Macintosh Drag and Drop extension.
• Scrapbook and System 7.1.2
The Scrapbook that supports Quickdraw 3D viewing is based on the Scrapbook that shipped
with System 7.5. Therefore you will need System 7.5 or greater to do QuickDraw 3D viewing.
• Drag and Drop
You can also drag out from the Scrapbook and the SimpleText by holding down the "Option" key, click inside the window and drag out.
